Documentation for self-hosting with docker compose #855

unteem · 2025-04-07T21:09:27Z

Purpose

Make self hosting of Docs easier with an example of a deployment procedure with docker compose and document how to configure Docs.

While #583 propose an easy way to deploy Docs with docker and Make, here we describe more in details the various steps and requirements to deploy Docs.

Proposal

example to deploy and configure keycloak
example to deploy and configure minio
example to configure proxy and certs
example to deploy and configure Docs

Improvements

Rephrase description of environment variables and categorize
Use template for nginx conf

Fixes #561
Supersedes #583

A one liner quick start could be a nice addition:

merge all services in a single compose
scripts to generate secrets

Signed-off-by: unteem <[email protected]> f

Signed-off-by: unteem <[email protected]>

sylvinus · 2025-04-11T14:08:45Z

docs/installation/compose.md

+docker compose pull
+```
+
+### Step 3: Restart yout containers


vnghia · 2025-04-24T17:50:31Z

docker/files/production/etc/nginx/conf.d/default.conf.template

+    location /collaboration-auth {
+        proxy_pass http://docs_backend/api/v1.0/documents/collaboration-auth/;
+        proxy_set_header X-Forwarded-Proto https;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Original-URL $request_uri;
+
+        # Prevent the body from being passed
+        proxy_pass_request_body off;
+        proxy_set_header Content-Length "";
+        proxy_set_header X-Original-Method $request_method;
+    }


I think we don't need this anymore as mentioned here. I am not sure if we still need /media-auth or not. I've managed to spin up docs with traefik without these two /collaboration-auth and /media-auth with socket connection and real time collaboration.

lunika

you commits does not have a description. It is useful to add it to explain why you made the modification about the env.md file for example.

lunika · 2025-04-28T09:19:46Z

docker/files/production/etc/nginx/conf.d/default.conf.template

+    location /collaboration/ws/ {
+        # Ensure WebSocket upgrade
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "Upgrade";
+
+        # Collaboration server
+        proxy_pass http://y-provider:4444;
+
+        # Set appropriate timeout for WebSocket
+        proxy_read_timeout 86400;
+        proxy_send_timeout 86400;
+
+        # Preserve original host and additional headers
+        proxy_set_header X-Forwarded-Proto https;
+        proxy_set_header Origin $http_origin;
+        proxy_set_header Host $host;
+    }
+
+    location /collaboration-auth {
+        proxy_pass http://docs_backend/api/v1.0/documents/collaboration-auth/;
+        proxy_set_header X-Forwarded-Proto https;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Original-URL $request_uri;
+
+        # Prevent the body from being passed
+        proxy_pass_request_body off;
+        proxy_set_header Content-Length "";
+        proxy_set_header X-Original-Method $request_method;
+    }


You can remove this part, it has been removed in the main branch, it is not used anymore.

lunika · 2025-04-28T09:31:05Z

docs/examples/compose/nginx-proxy/README.md

+curl -o compose.yaml https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/docs/examples/compose/nginx-proxy/compose.yaml
+```
+
+### Step 2: Edit `DEFAULT_EMAIL` in the compose file.


There is no description for this step 2.

lunika · 2025-04-28T09:31:17Z

docs/examples/compose/nginx-proxy/README.md

+
+### Step 2: Edit `DEFAULT_EMAIL` in the compose file.
+
+### Create docker network


Missing step 3

lunika · 2025-04-28T09:37:10Z

docs/installation/compose.md

+docker compose pull
+```
+
+### Step 3: Restart yout containers


Before restarting the containers you should suggest to read the UPGRADE.md file.

z3ntu · 2025-04-28T20:38:49Z

env.d/production.dist/common

+DOCS_HOST=docs.domain.tld
+KEYCLOAK_HOST=id.domain.tld
+S3_HOST=storage.domain.tld
+MINIO_HOST=storage.domain.tld


Is MINIO_HOST used?

z3ntu · 2025-04-28T20:40:36Z

env.d/production.dist/kc_postgresql

+POSTGRES_PASSWORD=<generate postgres password>
+PGDATA=/var/lib/postgresql/data/pgdata
+
+# Keyclaok postgresql configuration


z3ntu · 2025-04-28T20:43:03Z

docs/installation/compose.md

+
+```bash
+mkdir -p docs/env.d
+curl -o compose.yaml https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/docs/examples/compose.yaml


you put the compose.yaml in a different directory than docs/examples/compose.yaml

z3ntu · 2025-04-28T20:43:15Z

docs/installation/compose.md

+curl -o compose.yaml https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/docs/examples/compose.yaml
+curl -o env.d/common https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/docs/env.d/production.dist/common
+curl -o env.d/backend https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/docs/env.d/production.dist/backend
+curl -o env.d/yprovider https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/docs/env.d/production.dist/yprovider


missing env.d/postgresql?

z3ntu · 2025-04-28T21:21:45Z

docs/examples/compose/keycloak/README.md

+1. Navigate to the "Clients" tab.
+2. Click on the "Create client" button.
+3. Enter the client ID - e.g. `docs`.
+4. Enable "Client authentification" option.


Client authentication

z3ntu · 2025-04-28T21:34:00Z

docs/examples/compose/compose.yaml

+    env_file:
+    - env.d/backend
+    - env.d/postgresql
+    - env.d/common


I believe common needs to come before backend, otherwise you get errors like this

WARN[0000] The "DOCS_HOST" variable is not set. Defaulting to a blank string. WARN[0000] The "DOCS_HOST" variable is not set. Defaulting to a blank string. WARN[0000] The "S3_HOST" variable is not set. Defaulting to a blank string.

z3ntu · 2025-04-28T21:58:30Z

docs/installation/compose.md

+
+```bash
+docker compose run --rm app python manage.py migrate
+docker compose run --rm app python manage.py createsuperuser --email <admin email> --password <admin password>


"app" should be "backend"? also at the bottom of this file

z3ntu · 2025-04-28T21:58:52Z

docs/installation/compose.md

+
+Replace `<admin email>` with the email of your admin user and generate a secure password. 
+
+Your docs instance is now avalailable on the domain you defined, https://docs.yourdomain.tld.


avalailable

z3ntu · 2025-04-28T22:18:42Z

docs/examples/compose/compose.yaml

+    # - VIRTUAL_PORT=8083 # used by nginx proxy
+    # - LETSENCRYPT_HOST=${DOCS_HOST} # used by lets encrypt to generate TLS certificate
+    volumes:
+    - ./default.conf.template:/etc/nginx/templates/default.conf.template


I think /docker-entrypoint.d/20-envsubst-on-templates.sh is never run so the template never becomes a proper config.

The upstream nginx container uses ENTRYPOINT ["/docker-entrypoint.sh"] which should call this but this is overwritten in the lasuite/impress-frontend image to /usr/local/bin/entrypoint

Am I missing something?

unteem force-pushed the documentation-docker branch 2 times, most recently from 48a9bc4 to ae27df7 Compare April 8, 2025 06:37

unteem added 3 commits April 8, 2025 10:49

📝(doc): add documentation to install with compose

01e13f8

Signed-off-by: unteem <[email protected]> f

📝(doc): reformulate description of env var

2c94083

Signed-off-by: unteem <[email protected]>

📝(doc): split env variables description into categories

3531bf4

Signed-off-by: unteem <[email protected]>

unteem force-pushed the documentation-docker branch from ae27df7 to 3531bf4 Compare April 8, 2025 08:50

📝(doc): add REALM_NAME as a variable in docker example

ffd37f4

AntoLC requested a review from lunika April 8, 2025 19:23

sylvinus reviewed Apr 11, 2025

View reviewed changes

docs/installation/compose.md

docker compose pull

```

### Step 3: Restart yout containers

Copy link

Member

sylvinus Apr 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yout

unteem mentioned this pull request Apr 16, 2025

How to Deploy the Application Using Docker Compose with Nginx Reverse Proxy in Front #881

Open

vnghia reviewed Apr 24, 2025

View reviewed changes

lunika reviewed Apr 28, 2025

View reviewed changes

z3ntu reviewed Apr 28, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documentation for self-hosting with docker compose #855

Documentation for self-hosting with docker compose #855

unteem commented Apr 7, 2025

sylvinus Apr 11, 2025

vnghia Apr 24, 2025

lunika left a comment

lunika Apr 28, 2025

lunika Apr 28, 2025

lunika Apr 28, 2025

lunika Apr 28, 2025

z3ntu Apr 28, 2025

z3ntu Apr 28, 2025

z3ntu Apr 28, 2025

z3ntu Apr 28, 2025

z3ntu Apr 28, 2025

z3ntu Apr 28, 2025

z3ntu Apr 28, 2025

z3ntu Apr 28, 2025

z3ntu Apr 28, 2025


		### Step 2: Edit `DEFAULT_EMAIL` in the compose file.

		### Create docker network


		Replace `<admin email>` with the email of your admin user and generate a secure password.

		Your docs instance is now avalailable on the domain you defined, https://docs.yourdomain.tld.

Documentation for self-hosting with docker compose #855

Are you sure you want to change the base?

Documentation for self-hosting with docker compose #855

Conversation

unteem commented Apr 7, 2025

Purpose

Proposal

Improvements

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lunika left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment